Workflow - Transition Rules

🔁 Transition Rules – What, Why & How

Transition Rules define how a document moves from one Workflow State to another. Each rule specifies the current state, the next state, the role allowed to transition, the action label, and optionally, a condition.

These rules control both the flow logic and access permissions. They are essential for: - Preventing unauthorized actions - Enforcing sequential approvals - Automating field updates - Enabling conditional transitions (e.g., only allow approval if total amount < 100,000)

🧱 Fields in Transition Rules

Field	Purpose
State	Current state of the document
Action	Label/button that appears in the UI (e.g., “Approve”, “Reject”)
Next State	The state the document moves to on action
Allowed Role	Role permitted to perform the action
Condition (Optional)	Python expression to control when this transition is allowed
Allow Self Approval	Let the document owner approve their own documents (default: false)

📜 How to Write Conditions

The condition field allows you to use Python-like expressions to control when a transition is allowed.

Syntax:

doc.branch == frappe.session.user_branch

Examples:

Only approve if document total is less than 50,000:
```
doc.total < 50000
```

Only proceed if branch matches the current user’s branch:

doc.branch == frappe.db.get_value("Employee", frappe.session.user, "branch")

Only allow transition if the document has attachments:
```
len(doc.attachments) > 0
```

The doc object is the current document. You can also access frappe.db, frappe.session, and time utilities like frappe.utils.now().

👤 Restricting Workflow by Branch (Use Case: Branch Manager)

To restrict branch managers so they only see and approve documents from their own branch, do the following:

1. Add a branch field to your target DocType (e.g., Sales Invoice, Leave Application).

2. Assign branch field to each user (via Employee or User DocType).

3. Use a condition in the workflow transition:

doc.branch == frappe.db.get_value("Employee", frappe.session.user, "branch")

This ensures that only documents from the user’s own branch are eligible for transition.

4. Set role-based permissions in:

Role Permission Manager
Workflow Transition “Allowed Role” field

5. Email Notification Restriction:

Emails are only sent to users with access to act on a transition. Therefore, with the condition above in place, only branch-specific managers will be notified.

✅ Why This Matters

Without transition rules: - Any user with the right role might access or approve any document. - Data segregation (e.g., by branch, region) is impossible. - It’s hard to enforce granular security and compliance rules.

Using conditions with transitions helps to enforce data privacy, process hierarchy, and regional autonomy—all critical for growing businesses.